PostScript Figures

Most often your picture won't be made with commands; it will exist in a separate PostScript file. Inclusion of PostScript figures is still a bit of a bugaboo for many TEX users, in spite of the existence for many years now of Trevor Darrell's excellent macro package Psfig/TEX [#!psfig!#] and others.

The geom style automatically loads the file geompsfi.sty, a modified version of Psfig/TEX (incorporating some improvements by Stephan Bechtolsheim and others of my own). It allows you to include PostScript figures very simply:

\fig{PStorus}{The square torus}{A torus can be obtained, topologically,
by gluing together parallel sides of a square.}

The \fig macro takes the same three arguments (plus an optional one) as the Figure environment. But the first argument, in addition to being used to make a label, is also the name of the file where the PostScript figure is stored (minus the .ps suffix). Thus PStorus is stored in the file PStorus.ps.

To get two or three figures side by side, sharing the same caption, use \doublefig or \triplefig. The PostScript file names for \doublefig{foo}... would be in this case would be foo-1.ps and foo-2.ps, and likewise for \triplefig. There is no similar mechanism for more than three figures.

The directory where the figures are to be found is governed by the macro \picpath. For example, if the directory is called /u/levy/pictures, you should say

\def\picpath{/u/levy/pictures/}

to *You can also use a relative pathname, such as pictures/, or even the empty string (or ./) for the current directory. However, the program that sends your .dvi file to the printer may not find the pictures since it is likely to be invoked from a different directory.

If a pathname includes characters that are special to TEX, you need to make then unspecial in order to define \picpath. Here is an example:

\begingroup     % start a group so the change in _ is local
\catcode`\_=12  % make _ behave like an ordinary character
\gdef\picpath{/home/tampa_a/fac/wpt/pictures/} % this def is global
\endgroup       % now _ reverts to its usual meaning

If you have a long document with lots of pictures, it is better to organize them into sections and chapters. In that case you should leave \picpath unset, and set the macro \masterpicpath to the master picture directory. If I were using this scheme in this document, I might say

\def\masterpicpath{/home/levy/pictures/}

The way \fig works is by calling the command \psfig [#!psfig!#], which creates a TEX \vbox of the right size and containing instructions for the figure to be included at the time of printing. You normally won't use \psfig directly, since \fig calls it automaticaly.

to *However, occasionally you many want to use \psfig directly to take advantage of this macro's many options, such as resizing. See the Psfig/TEX manual [#!psfig!#] for details; but some of the newer options to Psfig/TEX are not supported here.

In order for the \psfig command to know what size box to make, it needs to find your PostScript figure file, and the file must have near the top a line like this:

%%BoundingBox: 0 30 98 128

Note that \psfig only cares about the height and the width of the bounding box, not about the actual values of the high and low coordinates. The latter are relevant only in reference to the coordinates of the objects inside the picture, about which \psfig knows nothing. (Thus the bottom left corner of the square in PStorus has coordinates (4, 34), which is a little bit above and to the right of the bounding box's bottom left corner (0, 30).) If one added the same number to the x-coordinates of the bounding box and of every object in the picture, the result would be exactly the same.

Normally, the %%BoundingBox line should have been placed in the PostScript file automatically, by whatever program you used to create the figure. If the program did not write a line like that, you have to do it by hand, and you should consider switching to another program.

Notice that the labels a and b in PStorus appear in the same font as they would in the text. In fact the labels were typeset by TEX itself, and do not come from the PostScript file, where it would be hard to specify them satisfactorily—especially details such as the placement of the primes and other subscripts and superscripts. The information for these labels is contained in a file with the suffix .lab, which normally is generated by the same program that creates the PostScript file, or by a postprocessor. If you want to include Mathematica graphics, for example, you should use the mathfig utility, described in the Appendix.

to *The average user has no need to know what the .lab file looks like, but if you want to write a new postprocessor in order to implement this labeling scheme in conjunction with your favorite drawing program, here are the details. Each line of the file yields one label, and contains the \setlabel command followed by five arguments: the text of the label, to be typeset in math mode; the x- and y-coordinates of the label's reference point, in points; and the relative x- and y-coordinates of the reference point. A value of 1 for the last two arguments means the reference point of the label it at the top or right of the label's bounding box; a value of -1 means bottom or left, a value of 0 means middle, and so on.

For example, here is the file PStorus.lab corresponding to PStorus:

\setlabel{a}{48.600000}{34.162104}{0}{1}
\setlabel{b}{4.162104}{78.600000}{1}{0}
\setlabel{a'}{48.600000}{123.037896}{0}{-1}
\setlabel{b'}{93.037896}{78.600000}{-1}{0}

If you want to typeset a label outside math mode, use 's \mbox command (or TEX's \hbox). The font used by default in this case is the same as for captions. Thus, to get the label foo you'll probably want to type the string \hbox{foo} into your figure-making program.

Sometimes the fact that the source \hbox{foo} has many more characters than the output causes problems—for example, the figure-making program might leave too much space for the label. The macro \hyperactivelabels provides a way around this. This macro is called every time a label is about to be typeset, and you can define it at will, to allow abbreviations, say. Thus, after the commands

\def\hyperactivelabels{\mathcode`:="8000}
\def\activecolon#1:{\hbox{#1}}
{\catcode`\:=\active\global\let:=\activecolon}

Utilities (programs) that generate PostScript graphics files generally start the file with a ``signature'' (a comment line stating the utility's name and version) and a chunk of PostScript code—call it a header—establishing abbreviations, subroutines, fonts and the like. The header is always the same, so if you have dozens of figures generated by the same utility it's good to factor out this commonality, if possible. With certain utilities, you can save your files without the header. Then they won't print on their own; but when \psfig looks into them, if it can recognize the utility's signature, it puts into the dvi file a command that causes the inclusion of the header at printing time. This way the header is included only once for all figures, saving memory and time. The utilities that \psfig currently knows about are Mathematica [#!wolfram!#] and Adobe Illustrator [#!illustrator!#]. With Illustrator, saving without the header is accomplished by clicking on the appropriate entry in the ``Save As'' dialog box. For Mathematica, see the Appendix.

to *For the signature to be seen by \psfig, it must appear near the top of the file; the actual number of lines that \psfig scans is controlled by the counter \maxheaderlines. The %%BoundingBox line must also lie in that same initial stretch. The default value of \maxheaderlines is 100, which is almost always adequate.